package com.example.service;

import com.example.entity.ChatSession;
import java.util.List;
import java.util.Optional;

/**
 * 聊天会话管理服务接口
 * 负责管理AI助手的对话会话生命周期
 */
public interface ChatSessionService {
    
    /**
     * 创建新的聊天会话
     * @param userId 用户ID
     * @return 新创建的会话
     */
    ChatSession createSession(Long userId);
    
    /**
     * 获取用户的会话
     * @param userId 用户ID
     * @param sessionId 会话ID
     * @return 会话信息，如果不存在则返回Optional.empty()
     */
    Optional<ChatSession> getSession(Long userId, String sessionId);
    
    /**
     * 获取用户的所有活跃会话列表
     * @param userId 用户ID
     * @return 用户的会话列表
     */
    List<ChatSession> getUserSessions(Long userId);
    
    /**
     * 保存会话信息
     * @param session 会话对象
     */
    void saveSession(ChatSession session);
    
    /**
     * 添加消息到指定会话
     * @param userId 用户ID
     * @param sessionId 会话ID
     * @param role 消息角色（user, assistant, system）
     * @param content 消息内容
     * @return 更新后的会话
     */
    ChatSession addMessage(Long userId, String sessionId, String role, String content);
    
    /**
     * 删除会话
     * @param userId 用户ID
     * @param sessionId 会话ID
     * @return 是否删除成功
     */
    boolean deleteSession(Long userId, String sessionId);
    
    /**
     * 归档会话
     * @param userId 用户ID
     * @param sessionId 会话ID
     * @return 是否归档成功
     */
    boolean archiveSession(Long userId, String sessionId);
    
    /**
     * 清理过期会话
     * @return 清理的会话数量
     */
    int cleanupExpiredSessions();
    
    /**
     * 获取用户的默认会话（如果不存在则创建）
     * @param userId 用户ID
     * @return 默认会话
     */
    ChatSession getOrCreateDefaultSession(Long userId);
    
    /**
     * 更新会话配置
     * @param userId 用户ID
     * @param sessionId 会话ID
     * @param config 新的配置
     * @return 是否更新成功
     */
    boolean updateSessionConfig(Long userId, String sessionId, ChatSession.SessionConfig config);
    
    /**
     * 重命名会话
     * @param userId 用户ID
     * @param sessionId 会话ID
     * @param newTitle 新标题
     * @return 是否重命名成功
     */
    boolean renameSession(Long userId, String sessionId, String newTitle);
} 